package com.xunshibao.core.dao;

import java.io.Serializable;
import java.util.List;
import java.util.Map;

import com.xunshibao.core.dao.page.Pagination;

/**
 * <pre>
 * dao处理接口
 * 需要注意的问题：<br/>
 * 凡是方法中包含了Named的字样，均表示使用hbm.xml中的命名查询，
 * 没有包含Named字样的方法均为程序中直接提供的HQL语句，另外所有
 * 的查询参数均是命名方式的，即:
 * <code>select user from User user where user.name=:username</code>
 * 请注意这里的:username
 * 
 * <pre>
 * @author eone
 * 
 */
public interface BaseDao extends GenericDao {

    /**
     * 查询
     * 
     * @param hql
     *            hql语句
     * @param params
     *            hql参数，key为参数名，value为参数值
     * @return 失败或异常返回null
     */
    public List<?> find(final String hql, final Map<String, Object> params);

    /**
     * 使用命名查询
     * 
     * @param queryName
     *            命名查询名称
     * @param params
     *            hql参数，key为参数名，value为参数值
     * @return
     */
    public List<?> findNamed(final String queryName, final Map<String, Object> params);

    /**
     * 仅查询一个对象
     * 
     * @param hql
     *            hql语句
     * @param params
     *            hql参数，key为参数名，value为参数值
     * @return 结果数不为1、失败或异常返回null
     */
    public Object findSingle(final String hql, final Map<String, Object> params);

    /**
     * 仅查询一个对象
     * 
     * @param hql
     *            命名查询名称
     * @param params
     *            hql参数，key为参数名，value为参数值
     * @return 结果数不为1、失败或异常返回null
     */
    public Object findNamedSingle(final String queryName, final Map<String, Object> params);

    /**
     * 返回记录数
     * 
     * @param hql
     *            count hql语句
     * @return 返回满足条件的记录数，如果不存在，返回 0， 异常返回null
     */
    public Long getRecordCount(String hql);

    /**
     * 
     * @param queryName
     *            count hql语句
     * @return 返回满足条件的记录数，如果不存在，返回 0
     */
    public Long getNamedRecordCount(String queryName);

    /**
     * count记录数
     * 
     * @param hql
     *            count hql语句
     * @param params
     *            hql参数，key为参数名，value为参数值
     * @return 返回满足条件的记录数，如果不存在，返回0
     */
    public Long getRecordCount(String hql, Map<String, Object> params);

    /**
     * count记录数
     * 
     * @param hql
     *            count hql语句
     * @param params
     *            hql参数，key为参数名，value为参数值
     * @return 返回满足条件的记录数，如果不存在，返回0
     */
    public Long getNamedRecordCount(String queryName, Map<String, Object> params);

    /**
     * 分页查询
     * 
     * @param hql
     *            hql语句
     * @param pageNo
     *            页码
     * @param pageSize
     *            页大小
     * @return 带分页信息的数据
     */
    public Pagination pageFind(String hql, int pageNo, int pageSize);

    /**
     * 分页查询
     * 
     * @param hql
     *            hql语句
     * @param params
     *            hql参数，key为参数名，value为参数值
     * @param pageNo
     *            页码
     * @param pageSize
     *            页大小
     * @return 带分页信息的数据
     */
    public Pagination pageFind(String hql, int pageNo, int pageSize, Map<String, Object> params);

    /**
     * 命名分页查询
     * 
     * @param queryName
     *            queryName的名称
     * @param pageNo
     *            页码
     * @param pageSize
     *            页大小
     * @return 带分页信息的数据
     */
    public Pagination pageNamedFind(String queryName, int pageNo, int pageSize);

    /**
     * 命名分页查询
     * 
     * @param queryName
     *            queryName的名称
     * @param params
     *            hql参数，key为参数名，value为参数值
     * @param pageNo
     *            页码
     * @param pageSize
     *            页大小
     * @return 带分页信息的数据
     */
    public Pagination pageNamedFind(String queryName, int pageNo, int pageSize, Map<String, Object> params);

    /**
     * 使用HQL语句更新数据库，包括update和delete
     * 
     * @param hql
     *            更新的HQL语句，包括update和delete
     * @param params
     *            hql参数，key为参数名，value为参数值
     * @return 成功返回更新的记录数，失败返回 -1
     */
    public int hqlUpdate(final String hql, final Map<String, Object> params);

    /**
     * 使用HQL语句更新数据库，包括update和delete
     * 
     * @param hql
     *            更新的HQL语句，包括update和delete
     * @return 成功返回更新的记录数，失败返回 -1
     */
    public int hqlUpdate(final String hql);

    /**
     * 使用HQL语句更新数据库，包括update和delete
     * 
     * @param queryName
     *            查询名称，包括update和delete
     * @param params
     *            hql参数，key为参数名，value为参数值
     * @return 成功返回更新的记录数，失败返回 -1
     */
    public int hqlNamedUpdate(final String queryName, final Map<String, Object> params);

    /**
     * 使用HQL语句更新数据库，包括update和delete
     * 
     * @param queryName
     *            查询名称，包括update和delete
     * @return 成功返回更新的记录数，失败返回 -1
     */
    public int hqlNamedUpdate(final String queryName);

    /**
     * 执行事务操作，可操作插入、删除或更新，不能做查询操作，如果需要查询参考find方法
     * 
     * @param lstExecuteHqls
     *            要执行事务操作的一系列hql语句
     * @return 异常或失败返回null，成功返回0
     */
     public int executeTransaction(final List<ExecuteHql> lstExecuteHqls);

    /**
     * 执行事务操作，可操作插入、删除或更新，不能做查询操作，如果需要查询参考find方法
     * 
     * @param lstExecuteHqls
     *            要执行事务操作的一系列TransactionItem语句
     * @return 异常或失败返回null，成功返回0
     */
     public int execTransaction(final List<TransactionItem>
     lstExecuteHqls);

    /**
     * <pre>
     * 执行DDL语句
     * </pre>
     * 
     * @param ddl
     */
    public void execDDL(String ddl);

    /**
     * <pre>
     * 用native sql语句查询列表,sql语句必须给出查询的列，不能用*,另外，如果需要用统计函数等，需要给出别名，
     * 别名会作为map的key
     * </pre>
     * 
     * @param sql
     *            native sql语句
     * @param params
     *            查询参数，参数必须以如下形式<br/>
     *            <code>select u.name from user u where u.id=:id</code>
     * @return 返回结果集列表，其中每一行是一个HashMap<String, Object>对象，<br/>
     *         如果不存在，返回空List
     */
    public List<Map<String, Object>> findSQL(String sql, Map<String, Object> params);

    /**
     * <pre>
     * 用native sql语句查询列表,sql语句必须给出查询的列，不能用*,另外，如果需要用统计函数等，需要给出别名，
     * 别名会作为map的key
     * </pre>
     * 
     * @param sql
     *            native sql语句
     * @return 返回结果集列表，其中每一行是一个HashMap<String, Object>对象，<br/>
     *         如果不存在，返回空List
     */
    public List<Map<String, Object>> findSQL(String sql);

    /**
     * <pre>
     * 用native sql语句查询列表,sql语句必须给出查询的列，不能用*,另外，如果需要用统计函数等，需要给出别名，
     * 别名会作为map的key
     * </pre>
     * 
     * @param sql
     *            native sql语句
     * @param params
     *            查询参数，参数必须以如下形式<br/>
     * @param startIndex
     *            起始记录位置
     * @param pageSize
     *            页大小 <code>select u.name from user u where u.id=:id</code>
     * @return 返回结果集列表，其中每一行是一个HashMap<String, Object>对象，<br/>
     *         如果不存在，返回空List
     */
    public List<Map<String, Object>> findSQL(final String sql, final Map<String, Object> params, final Integer startIndex,
            final Integer pageSize);

    /**
     * <pre>
     * 用native sql语句查询列表,sql语句必须给出查询的列，不能用*,另外，如果需要用统计函数等，需要给出别名，
     * 别名会作为map的key
     * </pre>
     * 
     * @param sql
     *            native sql语句
     * @param startIndex
     *            起始记录位置
     * @param pageSize
     *            页大小
     * @return 返回结果集列表，其中每一行是一个HashMap<String, Object>对象，<br/>
     *         如果不存在，返回空List
     */
    public List<Map<String, Object>> findSQL(String sql, final Integer startIndex, final Integer pageSize);

    /**
     * <pre>
     * 用native sql语句查询列表,sql语句必须给出查询的列，不能用*,另外，如果需要用统计函数等，需要给出别名，
     * 别名会作为map的key
     * </pre>
     * 
     * @param sql
     *            native sql语句
     * @param params
     *            查询参数，参数必须以如下形式<br/>
     *            <code>select u.name from user u where u.id=:id</code>
     * @return 返回结果是一个HashMap<String, Object>对象，<br/>
     *         如果不存在，返回null
     */
    public Map<String, Object> findSQLSingle(String sql, Map<String, Object> params);

    /**
     * <pre>
     * 用native sql语句查询列表,sql语句必须给出查询的列，不能用*,另外，如果需要用统计函数等，需要给出别名，
     * 别名会作为map的key
     * </pre>
     * 
     * @param sql
     *            native sql语句
     * @return 返回结果是一个HashMap<String, Object>对象，<br/>
     *         如果不存在，返回null
     */
    public Map<String, Object> findSQLSingle(String sql);

    /**
     * <pre>
     *  执行sql的更新语句，update, delete
     * </pre>
     * 
     * @param sql
     *            更新SQL语句
     * @param params
     *            更新参数，注意这里的参数的位置必须和查询语句里的位置一一对应<br/>
     *            第一个参数对应第一个位置，第二个参数对应第二个位置
     * @return 影响的行数
     */
    public int sqlUpdate(String sql, List<Object> params);

    /**
     * <pre>
     *  执行sql的更新语句，update, delete
     * </pre>
     * 
     * @param sql
     *            更新SQL语句
     * @return 影响的行数
     */
    public int sqlUpdate(String sql);

    /**
     * 获取指定sequence的下一个值
     * 
     * @param sequenceName
     *            sequence名称
     * @return sequence的下一个值
     */
    public Integer getSeqNextVal(String sequenceName);
}
